To generate an exception and cause control to return to the error handler, use the MESSAGE procedure. Calling MESSAGE generates an exception that sets the !ERROR_STATE system variable. !ERROR_STATE.MSG is set to the string used as an argument to MESSAGE.
The MESSAGE procedure is used by user procedures and functions to issue errors. It has the form:
MESSAGE, Text
where Text is a scalar string that contains the text of the error message.
The MESSAGE procedure issues error and informational messages using the same mechanism employed by built-in IDL routines. By default, the message is issued as an error, the message is output, and IDL takes the action specified by the ON_ERROR procedure.
As a side effect of issuing the error, appropriate fields of the system variable !ERROR_STATE are set; the text of the error message is placed in !ERROR_STATE.MSG, or in !ERROR_STATE.SYS_MSG for the operating system’s component of the error message. See !ERROR_STATE for more information.
As an example, assume the statement:
MESSAGE, 'Unexpected value encountered.'
is executed in a procedure named CALC. IDL would print:
% CALC: Unexpected value encountered.
and execution would halt.
The MESSAGE procedure accepts several keywords that modify its behavior. See MESSAGE for additional details.
Another use of MESSAGE involves re-signaling trapped errors. For example, the following code uses ON_IOERROR to read from a file until an error (presumably end‑of‑file) occurs. It then closes the file and reissues the error.
; Open the data file.
OPENR, UNIT, 'DATA.DAT', /GET_LUN
; Arrange for jump to label EOD when an input/output error occurs.
ON_IOERROR, EOD
; Read every line of the file.
WHILE 1 DO READF, UNIT, LINE
; An error has occurred. Cancel the input/output error trap.
EOD: ON_IOERROR, NULL
; Close the file.
FREE_LUN, UNIT
; Reissue the error. !ERROR_STATE.MSG contains the appropriate
; text. The IOERROR keyword causes it to be issued as an
; input/output error. Use of NONAME prevents MESSAGE from tacking
; the name of the current routine to the beginning of the message
; string since !ERROR_STATE.MSG already contains it.
MESSAGE, !ERROR_STATE.MSG, /NONAME, /IOERROR
IDL messages include text and formatting information which, when combined with text supplied in the call to MESSAGE, provide information to the program’s user about the error that occurred. For example, entering
MESSAGE, 'Howdy, folks'
at the IDL command line produces the following output:
% $MAIN$: Howdy, folks
% Execution halted at: $MAIN$
indicating that the message was issued from within the IDL $MAIN$ program.
A message block is a collection of messages that are loaded into IDL as a single unit. At startup, IDL contains a single internal message block named IDL_MBLK_CORE, which contains the standard messages required by the IDL system. By default, MESSAGE throws the IDL_M_USER_ERR message from the IDL_MBLK_CORE message block, producing output similar to that shown above.
Dynamically loadable modules (DLMs) usually define additional message blocks for their own needs when they are loaded. In addition, if you wish to provide something other than the default error message for your own IDL programs, you can define your own message blocks and error messages. See DEFINE_MSGBLK and DEFINE_MSGBLK_FROM_FILE for additional details. Specify the BLOCK and NAME keywords to the MESSAGE procedure to issue a message from a message block you have defined.